home *** CD-ROM | disk | FTP | other *** search
/ Windows Game Programming for Dummies (2nd Edition) / WinGamProgFD.iso / mac / DirectX SDK / DXSDK / samples / Multimedia / DirectPlay / VoiceConnect / readme.txt < prev    next >
Text File  |  2001-10-10  |  8KB  |  148 lines
  1. //-----------------------------------------------------------------------------
  2. // 
  3. // Sample Name: VoiceConnect Sample
  4. // 
  5. // Copyright (c) 1999-2001 Microsoft Corporation. All rights reserved.
  6. // 
  7. //-----------------------------------------------------------------------------
  8.  
  9.  
  10. Description
  11. ===========
  12.   VoiceConnect shows how to network other players using DirectPlay to
  13.   start a DirectPlay Voice chat session.  After joining or creating a 
  14.   session, the players may use computer microphone to talk to one other.  
  15.   Other players may join the game in progress at any time.  
  16.  
  17. Path
  18. ====
  19.   Source: DXSDK\Samples\Multimedia\DirectPlay\VoiceConnect 
  20.  
  21.   Executable: DXSDK\Samples\Multimedia\DirectPlay\Bin
  22.  
  23. User's Guide
  24. ============
  25.   Refer to User's Guide section of the SimplePeer sample for information
  26.   on how to connect.  After connecting, the host will be presented with a 
  27.   dialog to select the voice codec to use.  Typical voice applications will
  28.   what automatically select one, or present this to the user in some other 
  29.   fashion.  Once the chat session has begin, any client may alter the playback
  30.   or capture settings by clicking on "Setup".
  31.  
  32. Programming Notes
  33. =================
  34.   The VoiceConnect sample is very similar in form to the SimplePeer sample.  For 
  35.   detailed programming notes on the basics this sample, refer to Programming 
  36.   Notes section of the SimplePeer sample.
  37.  
  38.   The VoiceConnect differs by letting clients use DirectPlay Voice to talk
  39.   to each other using a computer microphone.  Here's how this is done:
  40.   
  41.   * Initialize DirectPlayVoice.  See NetVoice.cpp 
  42.        Before using voice you need a to establish a DirectPlay Voice session.
  43.        So after the DirectPlay session as been created, we call 
  44.        CNetVoice::Init().  In this simple sample, we this when
  45.        the main dialog is initializes.  This does the following:
  46.        
  47.          - Tests the audio setup with DirectPlay Voice. 
  48.            See VoiceSessionTestAudioSetup() in NetVoice.cpp. 
  49.               1. Creates a IDirectPlayVoiceTest with CoCreateInstance()
  50.               2. Calls IDirectPlayVoiceTest::CheckAudioSetup() with the 
  51.                  DVFLAGS_QUERYONLY flag.  This will return DVERR_RUNSETUP 
  52.                  if the setup wizard needs to be run.  If it happens then 
  53.                  we call IDirectPlayVoiceTest::CheckAudioSetup() without
  54.                  the DVFLAGS_QUERYONLY flag.  This will run the dialog
  55.                  based DirectPlay Voice setup wizard.  If it returns success 
  56.                  then we can continue on, otherwise handle the error in
  57.                  some fashion.
  58.               3. Release the IDirectPlayVoiceTest
  59.               
  60.          - If hosting, then we create the voice session:  
  61.            See VoiceSessionCreate() in NetVoice.cpp
  62.               1. Create a IDirectPlayVoiceServer with CoCreateInstance().
  63.                  Keep this interface around since we'll need it later on.
  64.               2. Call IDirectPlayVoiceServer::Initialize to register the 
  65.                  voice server message handler.  We also pass in the 
  66.                  DirectPlay interface here.
  67.               3. Fill out a DVSESSIONDESC struct with the session type, and
  68.                  the desired voice codec.
  69.               4. Call IDirectPlayVoiceServer::StartSession() passing in
  70.                  the DVSESSIONDESC struct.
  71.           
  72.           - If either hosting or joining, then connect to the session. 
  73.             See VoiceSessionConnect() in NetVoice.cpp
  74.             
  75.               1. Create a IDirectPlayVoiceClient with CoCreateInstance()
  76.                  Keep this interface around since we'll need it later on.
  77.               2. Call IDirectPlayVoiceClient::Initialize to register the 
  78.                  voice client message handler.  We also pass in the 
  79.                  DirectPlay interface here.
  80.               3. Fill out a DVSOUNDDEVICECONFIG struct with the guids
  81.                  for the DirectSound playback and capture devices.
  82.               3. Fill out a DVCLIENTCONFIG struct.  This struct is 
  83.                  filled out when with setup dlg.  More complex apps
  84.                  may want to do this a different way.  See VoiceConfigDlgProc() 
  85.                  in VoiceConnect.cpp.
  86.               4. Call IDirectPlayVoiceClient::Connect() with the 
  87.                  DVSOUNDDEVICECONFIG struct and the DVCLIENTCONFIG struct.
  88.               5. Call IDirectPlayVoiceClient::SetTransmitTargets()
  89.                  to the desired default target.  This sample sets the
  90.                  target to DVID_ALLPLAYERS.
  91.               6. Call IDirectPlayVoiceClient::GetSoundDeviceConfig() and
  92.                  check for DVSOUNDCONFIG_HALFDUPLEX to figure out if this 
  93.                  client is in half-duplex mode.  In half-duplex mode, the 
  94.                  client can not talk, but only listen. 
  95.  
  96.   * Handle voice client messages.  See DirectPlayVoiceClientMessageHandler                 
  97.       - Upon DVMSGID_CREATEVOICEPLAYER:
  98.             1. Since DPN_MSGID_CREATE_PLAYER set a player context, and that message
  99.                is guaranteed to be processed first.  We call GetPlayerContext()
  100.                to get the player's context value and cast the pointer into a 
  101.                player struct.  We enter a global CS lock here and everytime
  102.                we access a player struct.  This is needed to make the struct 
  103.                thread safe, since the same player struct may be accessed by
  104.                multiple threads at the same time.               
  105.             2. Now that we have the player's struct we addref it.  This 
  106.                extra count will be for voice layer.  Upon DVMSGID_DELETEVOICEPLAYER
  107.                we will release it.  This ensures that any voice messages
  108.                that come in will be working with a valid player struct.  
  109.             3. We check the DVMSG_CREATEVOICEPLAYER for DVPLAYERCAPS_HALFDUPLEX
  110.                to see if this player is in half-duplex mode.  If so, then
  111.                we store that value in the player's struct.  Later
  112.                we will update the UI according.  See DisplayPlayersInChat()
  113.                for how this is done.
  114.             4. Similar to DirectPlay, DirectPlay Voice stores 
  115.                context values for each voice player.  So in this sample we 
  116.                store the same value in both locations by setting 
  117.                pCreateVoicePlayerMsg->pvPlayerContext.
  118.        - Upon DVMSGID_DELETEVOICEPLAYER:
  119.             1. We update the UI accordingly if the local player isn't going away.                              
  120.             2. We release the player's struct since we addref'ed it 
  121.                in DVMSGID_CREATEVOICEPLAYER
  122.        - Upon DVMSGID_HOSTMIGRATED:
  123.             1. If DVMSG_HOSTMIGRATED has a non-NULL pdvServerInterface, then
  124.                we have become the new host.  The sample updates the UI to 
  125.                show this.
  126.        - Upon DVMSGID_GAINFOCUS and DVMSGID_LOSTFOCUS:
  127.             This means that the app has gained or lost focus.  Apps that 
  128.             have lost focus can not talk.  When focus is re-gained they can.
  129.             In this sample, it updates the UI accordingly.
  130.        - Upon DVMSGID_RECORDSTART
  131.               DVMSGID_RECORDSTOP, 
  132.               DVMSGID_PLAYERVOICESTART,
  133.               DVMSGID_PLAYERVOICESTOP:
  134.             These message lets us know when talking has stopped or started for 
  135.             the local client, and for remove clients.  This sample handles
  136.             these messages by updating the UI accordingly.
  137.       
  138.   * Clean up DirectPlay Voice.  See bottom of CNetVoice::Free in NetVoice.cpp
  139.         1. Disconnect from the voice session.  See VoiceSessionDisconnect()
  140.             - Calls IDirectPlayVoiceClient::Disconnect()
  141.             - Releases the IDirectPlayVoiceClient
  142.         2. Destroy the voice session if this is the host.  See VoiceSessionDestroy() 
  143.             - Calls IDirectPlayVoiceServer::StopSession()
  144.             - Releases the IDirectPlayVoiceServer
  145.            
  146.  
  147.  
  148.